/**
 * 预约管理相关类型定义
 *
 * @fileoverview 预约系统的核心类型定义文件，包含预约记录、批次管理、操作日志等数据结构。
 * 定义了预约系统中所有实体的接口和枚举类型，确保数据结构的一致性和类型安全。
 *
 * 主要类型：
 * - 预约记录管理（AppointmentManagement）
 * - 批量预约批次（BatchBooking）
 * - 操作日志记录（AppointmentOperationLog）
 * - 快速预约配置（QuickBookingConfig）
 * - 各种输入输出类型
 *
 * @author System
 * @version 1.0.0
 * @since 2024
 */

// ============================================================================
// 基础枚举类型
// ============================================================================

/**
 * 签发国家类型
 *
 * @description 证件签发国家的枚举类型
 * @example
 * - CN: 中国
 * - OTH: 其他国家
 */
export type IssuingCountry = 'CN' | 'OTH'

/**
 * 签发机关类型
 *
 * @description 证件签发机关的枚举类型
 * @example
 * - GD: 广东
 * - OTH: 其他机关
 */
export type IssuingAuthority = 'GD' | 'OTH'

/**
 * 预约状态类型
 *
 * @description 预约记录的生命周期状态
 * @example
 * - pending: 待处理
 * - booked: 已预约
 * - confirmed: 已确认
 * - cancelled: 已取消
 * - failed: 失败
 */
export type AppointmentStatus = 'pending' | 'booked' | 'confirmed' | 'cancelled' | 'failed'

/**
 * 预约模式类型
 *
 * @description 预约的创建和处理模式
 * @example
 * - manual: 手动创建
 * - quick: 快速预约
 * - batch: 批量处理
 * - auto: 自动化处理
 */
export type BookingMode = 'manual' | 'quick' | 'batch' | 'auto'

/**
 * 批次状态类型
 *
 * @description 批量处理批次的执行状态
 * @example
 * - created: 已创建
 * - running: 执行中
 * - paused: 已暂停
 * - completed: 已完成
 * - failed: 执行失败
 */
export type BatchStatus = 'created' | 'running' | 'paused' | 'completed' | 'failed'

/**
 * 操作类型
 *
 * @description 对预约记录执行的操作类型
 * @example
 * - create: 创建记录
 * - update: 更新记录
 * - book: 预约操作
 * - cancel: 取消预约
 * - release: 释放占号
 */
export type OperationType = 'create' | 'update' | 'book' | 'cancel' | 'release'

// ============================================================================
// 主要数据结构
// ============================================================================

/**
 * 预约管理记录
 *
 * @description 预约系统的核心数据结构，包含申请人信息、预约状态、时间安排等完整信息。
 * 每个预约记录代表一个预约申请的完整生命周期。
 *
 * @interface AppointmentManagement
 * @example
 * ```typescript
 * const appointment: AppointmentManagement = {
 *   id: 1,
 *   sequence_number: '20241225001',
 *   passport_number: 'P123456789',
 *   license_number: 'L987654321',
 *   full_name: '张三',
 *   email: 'zhangsan@example.com',
 *   phone_number: '13800138000',
 *   issuing_country: 'CN',
 *   issuing_authority: 'GD',
 *   service_type: 'renewal',
 *   preferred_dates: '["25-12-2024", "26-12-2024"]',
 *   priority: 1,
 *   is_placeholder: false,
 *   appointment_status: 'pending',
 *   office_code: 'HKLO',
 *   booking_mode: 'manual',
 *   // ... 其他系统字段
 * }
 * ```
 */
export interface AppointmentManagement {
  /** 记录唯一标识 */
  id: number
  /** 序列号，格式：YYYYMMDD + 随机数 */
  sequence_number: string
  /** 护照号码 */
  passport_number: string
  /** 驾照号码 */
  license_number: string
  /** 申请人姓名 */
  full_name: string
  /** 电子邮箱 */
  email: string
  /** 联系电话（可选） */
  phone_number?: string
  /** 签发国家 */
  issuing_country: IssuingCountry
  /** 签发机关 */
  issuing_authority: IssuingAuthority
  /** 服务类型 */
  service_type: string
  /** 首选日期列表（JSON数组字符串） */
  preferred_dates?: string
  /** 首选时间列表（JSON数组字符串） */
  preferred_times?: string
  /** 优先级（1-5，数字越小优先级越高） */
  priority: number
  /** 备注信息 */
  remarks?: string
  /** 是否为占号数据 */
  is_placeholder: boolean
  /** 是否为监控数据 */
  is_monitor: boolean
  /** 是否强制仅使用首选日期进行预约（命中首选以外日期不下单） */
  force_preferred_dates?: boolean

  // ====== 预约状态相关 ======
  /** 当前预约状态 */
  appointment_status: AppointmentStatus
  /** 预约参考号 */
  reference_number?: string
  /** 预约日期（YYYY-MM-DD 格式；兼容历史 DD-MM-YYYY） */
  appointment_date?: string
  /** 预约时间（HH:MM-HH:MM格式） */
  appointment_time?: string
  /** 时间段ID */
  timeslot_id?: string
  /** 办公地点代码 */
  office_code: string

  // ====== 系统字段 ======
  /** 所属批次ID */
  batch_id?: string
  /** 关联任务ID */
  job_id?: string
  /** 预约模式 */
  booking_mode: BookingMode
  /** 错误信息 */
  error_message?: string
  /** 原始响应 */
  raw_response?: string
  /** 重试次数 */
  retry_count: number
  /** 创建时间 */
  created_at: Date
  /** 更新时间 */
  updated_at: Date
  /** 预约成功时间 */
  booked_at?: Date
  /** 会话使用的 User-Agent（若留空由系统生成） */
  user_agent?: string
}

// 创建预约记录的输入类型
export interface CreateAppointmentInput {
  sequence_number?: string // 如果不提供会自动生成
  passport_number: string
  license_number: string
  full_name: string
  email: string
  phone_number?: string
  issuing_country?: IssuingCountry
  issuing_authority?: IssuingAuthority
  service_type?: string
  preferred_dates?: string[]
  preferred_times?: string[]
  priority?: number
  remarks?: string
  is_placeholder?: boolean
  is_monitor?: boolean
  force_preferred_dates?: boolean
  office_code?: string
  /** 可选：指定会话 User-Agent；不填则系统生成 */
  user_agent?: string
}

// 更新预约记录的输入类型
export interface UpdateAppointmentInput {
  full_name?: string
  email?: string
  phone_number?: string
  issuing_country?: IssuingCountry
  issuing_authority?: IssuingAuthority
  service_type?: string
  preferred_dates?: string[]
  preferred_times?: string[]
  priority?: number
  remarks?: string
  is_placeholder?: boolean
  is_monitor?: boolean
  force_preferred_dates?: boolean
  appointment_status?: AppointmentStatus
  reference_number?: string
  appointment_date?: string
  appointment_time?: string
  timeslot_id?: string
  office_code?: string
  error_message?: string
  raw_response?: string
  retry_count?: number
  /** 更新/回填会话 User-Agent（可选） */
  user_agent?: string
  /** 创建时间（用于导入时保留原始创建时间） */
  created_at?: Date
  /** 预约成功时间（用于导入时保留原始预约成功时间） */
  booked_at?: Date
}

// 预约操作日志
export interface AppointmentOperationLog {
  id: number
  appointment_id: number
  operation_type: OperationType
  operation_data?: string // JSON字符串
  result_status: string
  result_message?: string
  operator: string
  timestamp: Date
}

// 可用性缓存
export interface AvailabilityCache {
  id: number
  cache_key: string
  service_type: string
  office_code: string
  date: string // YYYY-MM-DD（兼容历史 DD-MM-YYYY）
  available_timeslots: string // JSON字符串
  total_slots: number
  available_slots: number
  last_updated: Date
  expires_at: Date
  source: string
}

// 时段信息
export interface TimeslotInfo {
  id: string
  start_time: string // HHMM
  end_time: string // HHMM
  display_time: string // HH:MM-HH:MM
  available: boolean
}

// Excel 导入行数据
export interface ExcelRowData {
  序号?: string
  护照号码: string
  驾照号码: string
  姓名: string
  邮箱地址: string
  电话号码?: string
  签发国家?: IssuingCountry
  签发机关?: IssuingAuthority
  服务类型?: string
  首选日期?: string // 逗号分隔（新统一称呼）
  首选时间?: string // 逗号分隔（新统一称呼）
  是否强制使用首选日期?: boolean | string
  优先级?: number
  备注?: string
  是否占号?: boolean | string
}

// Excel 导入结果
export interface ExcelImportResult {
  success: boolean
  total_rows: number
  success_count: number
  error_count: number
  errors: Array<{
    row: number
    column?: string
    message: string
    data?: any
  }>
  imported_ids: number[]
}

// 查询过滤器
export interface AppointmentFilters {
  appointment_status?: AppointmentStatus[]
  is_placeholder?: boolean
  is_monitor?: boolean
  priority?: number[]
  issuing_country?: IssuingCountry[]
  service_type?: string[]
  office_code?: string[]
  batch_id?: string
  date_range?: {
    start: string // YYYY-MM-DD
    end: string // YYYY-MM-DD
  }
  // 新增：按预约日期筛选（与上方 date_range: created_at 区分）
  appointment_date_range?: {
    start: string // YYYY-MM-DD 或 DD-MM-YYYY
    end: string // YYYY-MM-DD 或 DD-MM-YYYY
  }
  // 新增：按预约成功时间（booked_at）筛选
  booked_at_range?: {
    start: string // YYYY-MM-DD
    end: string // YYYY-MM-DD
  }
  search?: string // 搜索姓名、护照号、邮箱等
}

// 分页参数
export interface PaginationParams {
  page: number
  page_size: number
  sort_field?: string
  sort_order?: 'asc' | 'desc'
}

// 查询结果
export interface AppointmentListResult {
  appointments: AppointmentManagement[]
  total: number
  page: number
  page_size: number
  total_pages: number
}

// 批量操作请求
export interface BatchOperationRequest {
  appointment_ids: number[]
  operation: 'book' | 'cancel' | 'delete' | 'release' | 'update_priority' | 'delete_all'
  data?: any // 操作相关的数据
}

// 批量操作结果
export interface BatchOperationResult {
  success: boolean
  total_count: number
  success_count: number
  failed_count: number
  errors: Array<{
    appointment_id: number
    message: string
  }>
}
